home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / packer / uuinout / uuin.v1.03.doc < prev    next >
Text File  |  1995-03-09  |  9KB  |  232 lines
  1. $VER: uuIn.doc 1.03 (15.12.93)
  2.  
  3.         uuIn v1.03 by Nicolas Dade
  4.  
  5. uuIn version 1.03 is copyright 1993 by Nicolas Dade. All Rights
  6. Reserved. Permission is hereby granted for non-commercial
  7. duplication and distribution, and for distribution by BBSs which do
  8. not charge for downloads, and for distribution in disk collections
  9. which charge a nominal fee per disk. This is not shareware.
  10.  
  11. That out of the way, what is it?
  12.  
  13. It's a uuencoder to encode binary files into uuencoded text (an
  14. encoding scheme that is used to send binary files over links that
  15. only support textual characters---ie email and internet news)
  16.  
  17.  
  18. --Why is this encoder better than those already available?--
  19.  
  20. * It's very fast. (and it uses a different, even faster encode
  21.   routine if a 68020 or higher is detected) (It's 100% assembly)
  22.   (and that 020 routine works now---sorry about that 1.01 problem)
  23.  
  24. * It will automatically generate multiple output files using maximum
  25.   lines and/or maximum bytes limits, and prevent widow files that
  26.   contain no full data lines. (nn's :decode doesn't like them)
  27.  
  28. * the name and protection modes encoded in the begin line can be
  29.   specified, or intelligent defaults are used.
  30.  
  31. * Data lines are terminated with a checksum, and a size line is
  32.   added at the end of the data. (both can be disabled)
  33.  
  34. * It will take its input from its standard input and write its
  35.   output to standard output, as well as to and from files.
  36.  
  37. * It does its own io buffering using a user sizeable buffer, so
  38.   your harddrive won't be slowed by thrashing if uuIn's input and
  39.   output come from and go to that harddrive. (and it uses only one
  40.   buffer)
  41.  
  42. * It's pure and it's small---you can make it resident and it
  43.   won't cost you over 5K
  44.  
  45. * uuIn reports all errors and strange conditions with descriptive
  46.   error messages, and aborts if it is sent a break signal
  47.   (Control-C).
  48.  
  49.  
  50. --Requirements--:
  51.  
  52. 2.04 or higher.
  53.  
  54.  
  55. --Use--:
  56.  
  57. the template for uuIn is: INFILE,OUTFILE,NAME/K,MODE=PROTECTION/K,
  58.      MAXLINES/N,MAXBYTES/N,NOCS=NOCHECKSUM/S,NOSIZE/S,NORENAME/S,
  59.      BUFSIZE/K/N,VERBOSE/S.
  60.  
  61. INFILE....the file from which to read the data to be encoded. If no
  62.       INFILE is specified, standard-in is used.
  63.  
  64. OUTFILE...the file to which the encoded data should be written. If
  65.       MAXLINES or MAXBYTES is used then OUTFILES is used as a
  66.       basename for the multiple files, numbered 1 through n with
  67.       as many leading zeros as needed (using an intelligent
  68.       amortized-cost-1 algorithm---use VERBOSE and you'll see :)
  69.  
  70. NAME......you can specify the name to store in the encoded data
  71.       (on the begin line). The default is the FilePart() of
  72.       INFILE. If you are not using INFILE (if you are using
  73.       standard-in) then NAME must be specified.
  74.  
  75. MODE=PROTECTION lets you specify the un*x protection mode to store
  76.       in the encoded data. This can be given two ways: three
  77.       octal digits (i.e. 644) or a seqence of rwx- (i.e.
  78.       rw-r--r--) which I personally find more readable. The
  79.       default is to copy the protection bits of INFILE or assume
  80.       644 if standard-in is used. The amiga protection bits are
  81.       translated to un*x as follows:
  82.       amiga read               -> un*x read for everyone
  83.       amiga write and amiga delete -> un*x write for owner
  84.       amiga execute            -> un*x execute for everyone
  85.  
  86. MAXLINES..If you want to generate multiple output files each of
  87.       which has no more than a certain number of lines, MAXLINES
  88.       will let you specify that limit. See OUTFILE and examples
  89.       for description of filenames generated. If no OUTFILE is
  90.       used (standard-out is used) then no limits may be
  91.       specified.
  92.  
  93. MAXBYTES..Similar to MAXLINES but puts a byte limit in the files. Both
  94.       MAXBYTES and MAXLINES can be specified, in which case each
  95.       file will be withing both limits.
  96.  
  97. NOCS=NOCHECKSUM...Keeps uuIn from adding a checksum to each data
  98.       line. The checksums are similar to the 'X's ADDX adds
  99.       except that they allows the decoder to double-check that
  100.       the data in the line is ok.
  101.  
  102. NOSIZE....Keeps uuIn from adding a size line at the end of the
  103.       data, right after the end line. This line is used by
  104.       decoders to double check that the file they decoded was
  105.       all there (has the correct size).
  106.  
  107. NORENAME..Keeps uuIn from renaming output files when uuIn is producing
  108.       mutiple output files and the digits uuIn is appending
  109.       to the filenames overflow the number of characters uuIn
  110.       has allocated for them. For example, when uuIn goes
  111.       from "out.uu.9" to "out.uu.10" it will try to rename "out.uu.1"
  112.       through "out.uu.9" to "out.uu.01"..."out.uu.09". This can
  113.       cause problems if the device it is outputting on does not
  114.       support renames. (i.e pipe:)
  115.  
  116. BUFSIZE...allows you to specify the size of the io buffer uuIn should
  117.       use in kilobytes. The default is 32K which is a little
  118.       small for a harddrive to harddrive encode. If you specify a
  119.       buffer larger than your largest block of free ram uuIn
  120.       will keep decreasing the size by half, trying to get some
  121.       buffer, until the buffer would be under 1K, at which point
  122.       uuIn gives up. If you don't even have 1K free you're in
  123.       more trouble than just having uuIn refuse to run. :)
  124.  
  125.       Specifying 0 means some thing special: uuIn will use a buffer
  126.       as large as the file (again, subject to the availability
  127.       of memory). Naturally this does not work with pipes (uuIn falls
  128.       back on the default 32K).
  129.  
  130.       In any case the buffer is always 1K, and never more than
  131.       MAXBYTES or 63*MAXLINES, whichever is smaller.
  132.  
  133. VERBOSE...progress reports are written to standard error.
  134.  
  135.  
  136. --Examples--:
  137.  
  138. To encode the file "binaryfile" and put the results in the file
  139. "uuedata"
  140.  
  141.   uuIn binaryfile uuedata
  142.  
  143. and to use 150K io buffers instead of the default 32L when doing
  144. this
  145.  
  146.   uuIn binaryfile uuedata BUFSIZE=150
  147.  
  148. To split the output into as many files as are needed to keep each
  149. file under 9Kbyes and under 900 lines (which ever comes first)
  150.  
  151.   uuIn binaryfile uuedata MAXLINES=900 MAXBYTES=9000
  152.  
  153. and files called "uuedata1", "uuedata2", etc will be created. If
  154. this takes more than 9 files then first file will be called
  155. "uuedata01". If this takes more than 99 files then first file will
  156. be called "uuedata001", etc.
  157.  
  158. To encode the standard input stream and output the result to the
  159. standard output stream, while naming the encoded data "mydata"
  160.  
  161.   uuIn NAME=mydata
  162.  
  163. and to encode its protection as rw-r-----
  164.  
  165.   uuIn NAME=mydata MODE=rw-r-----
  166.  
  167. And as usual, to see the template
  168.  
  169.  uuIn ?
  170.  
  171. and to see the full builtin help and copyright text, give a
  172. second "?" at the prompt following the template.
  173.  
  174.  
  175. --Speed Comparisons--:
  176.  
  177. On a 7.14MHz NTSC 68000 based Amiga (ie A500, A1000 or A2000) using
  178. the command line "uuIn ram:310KByteFile ram:440KByteOutput", encoding
  179. the 310Kbyte file which produces a 440 KByte uuencoded file:
  180.  
  181. using:      version:    takes:        speed:
  182. uuIn      1.03        5.4 secs       57Kb/s
  183. UUEncodeX 1.02           13.1 secs       24KB/s (using NOCHECK option)
  184. UUxT      2.2           50.0 secs    6Kb/s
  185.  
  186. and on a 22 MHz 68030 the same command took
  187.  
  188. uuIn      1.03        1.0 secs      310Kb/s
  189.  
  190.  
  191. --Widow Files--:
  192.  
  193. If the last outfile would contain no full data lines---just any of
  194. the final partial line, the empty line, the end line and the size
  195. line---then that file is not created. Instead the output is placed at
  196. the end of the previous file. This is done because nn (an internet
  197. news reader) and other "join and uudecode multiple parts" programs do
  198. not handle widow files correctly (BTW my uudecoder, uuOut, does). This
  199. may push the previous file over the MAXLINES and/or MAXBYTES limits.
  200. If this happens uuIn will warn you. The widow lines are never more
  201. than 5 lines and 87 bytes.
  202.  
  203.  
  204. --I can be reached at--:
  205.  
  206.  Nicolas Dade
  207.  405 W Delaware
  208.  Urbana, IL 61801  (USA)
  209. nicolas-dade@uiuc.edu
  210.  
  211.  
  212. --History--:
  213.  
  214. 1.00  o First version debugged enough to pass around.
  215. 1.01  o Improved the inteligence of the buffer allocation
  216.     routine, and made it use only one buffer.
  217.       o Messages directed at the user are sent through std-error
  218.     (Process_CES).
  219. 1.02  o Grrrrr. 1.01's 020 code had a ".b" that should have been a
  220.     ".w".
  221.       o Since Alan T Shutko so nicely sent me the code for the
  222.     checksums, I added it in.
  223.       o Thanks to Marcus Damberger for testing this version of
  224.     uuIn on his 030 machine.
  225. 1.03  o Make checksums and size lines the default.
  226.       o Wrote uuPrepare.rexx which wraps uuIn's output with a header,
  227.     a head line and a tail line.
  228.       o Added NORENAME for uuPrepare.rexx.
  229.       o Removed ADDX for lack of a purpose.
  230.       o Thanks to Olivier Jeannet for testing the final version.
  231.  
  232.